<!DOCTYPE html>
<html lang="en">

<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="description" content="Contributing to the GCC project." />
<meta name="keywords"
      content="GCC, standards, copyright, patches, contributing" />
<title>Contributing to GCC</title>
<link rel="stylesheet" type="text/css" href="https://gcc.gnu.org/gcc.css" />
</head>

<body>
<h1>Contributing to GCC</h1>

<p>We strongly encourage contributions in the form of features, new
or improved optimizations, bug fixes, documentation updates, web page
improvements, etc....</p>

<p>There are certain legal requirements and style issues which
contributions must meet:</p>

<ul>
<li><a href="#legal">Legal Prerequisites</a></li>
<li><a href="#standards">Coding Standards</a></li>
<li><a href="#testing">Testing Patches</a></li>
<li><a href="#docchanges">Documentation Changes</a></li>
<li><a href="#webchanges">Web Site Changes</a></li>
<li><a href="#patches">Submitting Patches</a></li>
<li><a href="#announce">Announcing Changes (to our Users)</a></li>
</ul>

<hr />

<h2 id="legal">Legal Prerequisites</h2>

<p>Before we can incorporate significant contributions, certain
legal requirements must be met.</p>

<p>The FSF prefers that a contributor files a copyright assignment for
large contributions.
<a href="https://www.gnu.org/prep/maintain/maintain.html#Legal-Matters">See
some documentation by the FSF</a> for details and contact us (either via
the <a href="mailto:gcc@gcc.gnu.org">gcc@gcc.gnu.org</a> list or the
GCC maintainer that is taking care of your contributions) to obtain
the relevant forms.  The most common forms are an assignment for a
specific change, an assignment for all future changes, and an employer
disclaimer, if an employer or school owns work created by the developer.
It's a good idea to send
<a href="mailto:assign@gnu.org">assign@gnu.org</a> a copy of
your request.</p>

<p>Alternatively, a contributor can certify the
<a href="https://developercertificate.org">Developer Certificate of Origin</a>
for their contribution by adding
the <a href="dco.html"><code>Signed-off-by:</code></a> tag to their submission.
Contributors with
<a href="https://gcc.gnu.org/gitwrite.html">commit access</a> can certify the
DCO for all future commits by adding their name to the DCO list in the
MAINTAINERS file.

<p>We can accept small changes without copyright assignment or DCO
certification.</p>

<h2 id="standards">Coding Standards</h2>

<p>All contributions must conform to the <a
href="https://www.gnu.org/prep/standards/">GNU Coding Standards</a>.
There are also some <a href="codingconventions.html">additional coding
conventions for GCC</a>; these include documentation and testsuite
requirements as well as requirements on code formatting.</p>

<p>Submissions which do not conform to the standards will be returned
with a request to address any such problems.  To help with the
preparation of patches you can use the script <a href=
"https://gcc.gnu.org/git/?p=gcc.git;a=blob;f=contrib/check_GNU_style.sh">
contrib/check_GNU_style.sh</a>.</p>

<!-- also referenced from gitwrite.html -->
<h2 id="testing">Testing Patches</h2>

<p>All patches must be thoroughly tested.  We encourage you to test
changes with as many host and target combinations as is practical.  In
addition to using real hardware, you can
<a href="simtest-howto.html">use simulators</a>.</p>

<p>Much of GCC's code is used only by some targets, or used in quite
different ways by different targets.  When choosing targets to test a
patch with, make sure that your selections exercise all aspects of the
code you are changing.</p>

<p>You will of course have tested that your change does what you
expected it to do: fix a bug, improve an optimization, add a new
feature.  Where possible you should automate these
tests and add them to GCC's testsuite.  You must also perform
regression tests to ensure that your patch does not break anything
else.  Typically, this means comparing post-patch test results to
pre-patch results by testing twice or comparing with recent posts to
the <a href="https://gcc.gnu.org/ml/gcc-testresults/">gcc-testresults
list</a>.</p>

<h3>Which tests to perform</h3>

<p>If your change is to code that is not in a front end, or is to the
C or C++ front ends, you must perform a complete build of GCC and the
runtime libraries included with it, on at least one target.  You must
bootstrap all default languages, not just C and C++, and run all testsuites.
For a normal native configuration, running</p>
<blockquote><pre>
make bootstrap
make -k check
</pre></blockquote>
<p>from the top level of the GCC tree (<strong>not</strong> the
<code>gcc</code> subdirectory) will accomplish this.</p>

<p>If your change is to a front end other than the C or C++ front end,
or a runtime library other than <code>libgcc</code>, you need to verify
only that the runtime library for that language still builds and the
tests for that language have not regressed.  (Most languages have
tests stored both in the <code>gcc</code> subdirectory, and in the
directory for the runtime library.)  You need not bootstrap, or test
other languages, since there is no way you could have affected
them.</p>

<p>Since the Ada front end is written in Ada, if you change it you
must perform a complete bootstrap; however, running other language
testsuites is not necessary.</p>

<p>In all cases you must test exactly the change that you intend to
submit.  The tree where you perform this test should not have any
other changes applied.</p>


<h2 id="docchanges">Documentation Changes</h2>

<p>Documentation changes do not require a new bootstrap (a working
bootstrap is necessary to get the build environment correct), but you
must perform <code>make info</code> and <code>make dvi</code> and correct
any errors.  You should investigate complaints about overfull or
underfull hboxes from <code>make dvi</code>, as these can be the only
indication of serious markup problems, but do not feel obliged to
eliminate them all.</p>


<h2 id="webchanges">Web Site Changes</h2>

<p>Changes to the web site must
<a href="https://validator.w3.org">validate</a> as HTML 5.  To
validate your changes, use the "upload file" mode of the
validator.</p>

<p>Please mark patches with the tag [wwwdocs] in the subject line.</p>

<p>More <a href="about.html#git">about our web pages</a>.</p>


<h2 id="patches">Submitting Patches</h2>

<p>Every patch must have several pieces of information, <em>before</em> we
can properly evaluate it:</p>

<dl>

<dt>A description of the problem/bug and how your patch addresses it.</dt>
<dd>
For new features a description of the feature and your implementation.
For bugs a description of what was wrong with the existing code, and a
reference to any previous bug report (in the
<a href="https://gcc.gnu.org/bugzilla/">GCC bug tracker</a>) and any
existing testcases for the problem in the GCC testsuite.
</dd>

<dt>Testcases</dt>
<dd>
If you cannot follow the recommendations of the <a
href="codingconventions.html">GCC coding conventions</a> about
testcases, you should include a justification for why adequate
testcases cannot be added.
</dd>

<dt>ChangeLog</dt>
<dd>
A ChangeLog entry as plaintext; see the <a href="codingconventions.html#ChangeLogs">GCC
coding conventions</a> and <a
href="http://www.gnu.org/prep/standards_toc.html">GNU Coding
Standards</a> for further information.

<br/>The <code>git gcc-commit-mklog</code> command from
<code>gcc-git-customization.sh</code> (see <a href="gitwrite.html">here</a>)
automates a lot of ChangeLog generation.
</dd>
<dt>Bootstrapping and testing</dt>
<dd>
State the host and target combinations you used to do <a
href="#testing">proper testing</a> as described above, and the results
of your testing.
</dd>

<dt>The patch itself</dt>
<dd>
Do not include generated files as part of the patch, just mention
them in the ChangeLog (e.g., "<code>* configure: Regenerate.</code>"). 
</dd>

</dl>

<p>Don't mix together changes made for different reasons.  Send them
<em>individually</em>.  Ideally, each change you send should be
impossible to subdivide into parts that we might want to consider
separately, because each of its parts gets its motivation from the
other parts.  In particular, changes to code formatting to conform to
coding standards are best not mixed with substantive changes, because
that makes it difficult to see what the real changes are.  (In the
case of a very large reorganization of code, it may make sense to
separate changes even further to make it clearer what has changed; for
example, by first sending structural changes that make subsequent
changes easier but do not change GCC's behavior, then new code, then
the changes that actually make use of the new code and change GCC's
behavior.)</p>

<p>We prefer patches posted as plain text or as MIME parts of type
<code>text/x-patch</code> or <code>text/plain</code>.
It is strongly discouraged to post patches as MIME parts of type
<code>application/</code><i>whatever</i>, disposition
<code>attachment</code> or encoded as <code>base64</code> or
<code>quoted-printable</code>.</p>

<p> If the patch is too big or too mechanical, posting it gzipped or
bzip2ed and uuencoded or encoded as a <code>base64</code> MIME part is
acceptable, as long as the ChangeLog is still posted as plain text.
</p>

<p>When you have all these pieces, bundle them up in a mail message and
send it to <a href="lists.html">the appropriate mailing list(s)</a>.
(Patches will go to one or more lists depending on what you are
changing.)  For further information on our source repository, see
the <a href="git.html">Anonymous read-only Git access</a> and <a
href="gitwrite.html">Read-write Git access</a> pages.</p>

<p>(Everything listed here still applies if you can check in the patch
without further approval under the <a
href="gitwrite.html#policies">GCC write access policies</a>, except
that ChangeLog entries may be included as part of the patch and diffs
representing new files may be omitted, especially if large, since they
can be accessed directly from the repository.)</p> 

<h3>E-mail subject lines</h3>

<p>Your contribution e-mail subject line will become the first line of
the commit message for your patch.</p>

<p>A high-quality e-mail subject line for a contribution contains the
following elements:</p>

<ul>
  <li>A classifier</li>
  <li>Component tags</li>
  <li>An optional series identifier</li>
  <li>A brief summary</li>
  <li>An optional bug number</li>
</ul>

<p>The entire line (excluding the classifier) should not exceed 75
characters.</p>

<h4>Classifier</h4>

<p>The classifier identifies the type of contribution, for example a
patch, an RFC (request for comments) or a committed patch (where
approval is not necessary.  The classifier should be written in upper
case and surrounded with square brackets.  This is the only component
of the e-mail subject line that will not appear in the commit itself.
The classifier may optionally contain a version number (v<i>N</i>) and
a series marker (<i>N/M</i>).  Examples are:</p>

<ul>
  <li><code>[PATCH]</code> - a single patch</li>
  <li><code>[PATCH v2]</code> - the second version of a single patch</li>
  <li><code>[PATCH 3/7]</code> - the third patch in a series of seven
    patches</li>
  <li><code>[RFC]</code> - a point of discussion, may contain a patch</li>
  <li><code>[COMMITTED]</code> - a patch that has already been committed.</li>
</ul>

<h4>Component tags</h4>

<p>A component tag is a short identifier that identifies the part of
the compiler being modified.  This highlights to the relevant
maintainers that the patch may need their attention.  Multiple
components may be listed if necessary.  Each component tag should be
followed by a colon.  For example,</p>

<ul>
  <li><code>libstdc++:</code></li>
  <li><code>combine:</code></li>
  <li><code>vax: testsuite:</code></li>
</ul>

<p>Some large components may be subdivided into sub-components.  If
the subcomponent name is not disctinct in its own right, you can use the
form <i>component/sub-component:</i>.</p>

<h4>Series identifier</h4>

<p>The series identifier is optional and is only relevant if a number of
patches are needed in order to effect an overall change.  It should be
a <i>short</i> string that identifies the series (it is common to all
patches) and should be followed by a single dash surrounded by white
space.</p>

<h4>A Very Brief summary</h4>

<p>The brief summary encapsulates in a few words the intent of the
change.  For example: <code>cleanup check_field_decls</code>.
Although, very short, the summary should be distinct so that it will
not be confused with other patches.</p>

<h4>Bug number</h4>

<p>If your patch relates a bug in the compiler for which there is an
existing PR number the bug number should be stated.  Use the
short-form variant <code>[PR<i>nnnnn</i>]</code> without the bugzilla
component identifier and with no space between 'PR' and the number.
The body of the commit message should still contain the full form
(<code>PR &lt;component&gt;/<i>nnnnn</i></code>) within the body of
the commit message so that Bugzilla will correctly notice the
commit.  If your patch relates to two bugs, then write
<code>[PR<i>nnnnn</i>, PR<i>mmmmm</i>]</code>.  For multiple
bugs, just cite the most relevant one in the summary and use an
elipsis instead of the second, or subsequent PR numbers; list all the
related PRs in the body of the commit message in the normal way.</p>

<p>It is not necessary to cite bugs that are closed as duplicates of
another unless there is something specific to that report that
is not covered by the parent bug.</p>

<h4>Other messages</h4>

<p>Some large patch sets benefit from an introductory e-mail that
provides more context for the patch series and describes how the
patches have been broken up to provide for review.  The convention is
that such messages should follow the same format as described above,
but the patch number should be set to zero, for example: <code>[PATCH
0/7]</code>.  Remember that the introductory message will not be
committed with the patches themselves, so it should not contain any
important information that is not also covered in the individual
patches.  If you send a summary e-mail with a series it is a good idea
to send the patches as follow-ups (essentially replies) to your
initial message so that mail software can group the messages
together.</p>

<p>If you submit a new version of a patch series, then you should
start a new email thread (don't reply to the original patch series).
This avoids email threads becoming confused between discussions of the
first and subsequent revisions of the patch set.  Your cover leter
(0/<i>nnn</i>) should explain clearly what has been changed between
the two patch series.  Also state if some of the patches are unchanged
between revisions; this saves maintainers having to re-review the
patches they might have already reviewed in an earlier version.  The
individual patch messages should be as you expect them to be
committed.  It is a good idea to send a final follow-up message to the
original thread indicating that a new version has been submitted.</p>

<h4>Examples</h4>

<p>Here are some complete examples, based on real commits to GCC.</p>

<ul>
  <li><code>[COMMITTED] libstdc++: Fix freestanding build [PR92376]</code></li>
  <li><code>[PATCH 1/6] analyzer: Fix tests for UNKNOWN_LOCATION</code></li>
  <li><code>[RFC] doc: Note that some warnings depend on optimizations [PR92757]</code></li>
  <li><code>[COMMITTED] c++: coroutines - Initial implementation</code></li>
  <li><code>[PATCH v2] wwwdocs: E-mail subject lines for contributions</code></li>
</ul>

<h4>git format-patch/send-email</h4>

The <code>git format-patch</code> tool generates an email in the desired
format, with the commit subject line as the email subject line
with <code>[PATCH]</code> prepended.  You can send the resulting file as an
email by itself (perhaps with <code>git send-email</code>) or as an attachment
to another email.

<h3>Pinging patches, Getting patches applied</h3>

<p>If you do not receive a response to a patch that you have submitted
within two weeks or so, it may be a good idea to chase it by sending a
follow-up e-mail to the same list(s).  Patches can occasionally fall
through the cracks.  Please be sure to include a brief summary of the
patch and the URL of the entry in the mailing list archive of the
original submission.</p>

<p>If you do not have write access and a patch of yours has been approved,
but not committed, please advise the approver of that fact.  You may want
to point out lack of write access in your initial submission, too.</p>
 

<h2 id="announce">Announcing Changes (to our Users)</h2>

<p>Everything that requires a user to edit their Makefiles or source code
is a good candidate for being mentioned in the release notes.</p>

<p>Larger accomplishments, either as part of a specific project, or long
term commitment, merit mention on the front page.  Examples include projects
like tree-ssa, new back ends, major advances in optimization or standards
compliance.</p>

<p>The gcc-announce mailing list serves to announce new releases and changes
like front ends or back ends being dropped.</p>

</body>
</html>
